﻿<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML><HEAD><TITLE>
Hercules: Telnet Support
</TITLE>
<LINK REL=STYLESHEET TYPE="text/css" HREF="hercules.css">
<link rel="shortcut icon" href="images/favicon.ico" />
<link rel="icon" href="images/favicon.ico" />

<!-- define a table style for consistent layout and presentation. -->

<style>
table {
    border: 2px solid black;
    border-collapse:collapse;
}
th {
    border: 1px solid black;
    vertical-align:bottom;
    padding:10px 5px 5px 5px;
}
td {
    border: 1px solid black;
    vertical-align: top;
    padding:5px 5px 10px 5px;
}
</style>

</HEAD><BODY BGCOLOR="#ffffcc" TEXT="#000000" LINK="#0000A0" VLINK="#008040" ALINK="#000000">

<h1 id="pagetop">Telnet/tn3270 Console How-To for Hercules Version 4</h1>

<hr noshade>

<p>Hercules Version 4 has been used with the following tn3270 and telnet
applications. Click on each name to view settings and other considerations
for using that application with Hercules.</p>
    <ul>
        <li><a href="#x3270">x3270 / c3270 / wc3270 tn3270</a> - Windows, Linux; no license fee</li>
        <li><a href="#OSXtn3270">Tn3270 for the Macintosh</a> - OS X (multiple versions); no license fee</li>
        <li><a href="#Vistatn3270">Vista tn3270</a> - Windows; nominal license fee</li>
        <li><a href="#ZOCTerminal">ZOC Terminal</a> - Windows, OS X; nominal license fee</li>
        <li><a href="#PuTTY">PuTTY Telnet</a> - Windows, Linux; no license fee</li>
    </ul>
    <ul>
        <li><a href="#nixtelnet">Linux telnet</a> - The default Linux telnet client works well OOTB</li>
        <li><a href="#Windows">Windows Telnet</a> - Windows has been used, others are likely to work</li>
        <li><a href="#WindowsNT">Windows NT Telnet</a> - Windows NT only</li>
    </ul>
<p>
    The above list is neither an endorsement of those products nor a recommendation
    to use them. If wish to share your experience with a different telnet and/or
    tn3270 application, please post that experience to the
    <a href="https://hercules-390.groups.io/g/group" target="_blank">Hercules-390
    discussion group</a>. Other telnet client applications that comply with the following
    RFCs should work.
</p>
<p>
    Remember that <b>local echo</b> needs to be set on for telnet connections.
</p>
<table style="border-style:none">
    <tr style="border-style:none;text-align:center">
        <th style="border-style:none">Telnet</th>
        <th style="border-style:none">    </th>
        <th style="border-style:none">tn3270</th>
    </tr>
    <tr style="border-style:none">
        <td style="border-style:none">
            <ul>
            <li><a href="http://www.rfc-editor.org/info/rfc854" target="_blank">RFC854 Telnet Protocol Specification</a></li>
            <li><a href="http://www.rfc-editor.org/info/rfc855" target="_blank">RFC855 Telnet Option Specifications</a></li>
            <li><a href="http://www.rfc-editor.org/info/rfc1091" target="_blank">RFC1091 Telnet terminal-type option</a></li>
            <li><a href="http://www.rfc-editor.org/info/rfc1143" target="_blank">RFC1143 The Q Method of Implementing TELNET Option Negotiation</a></li>
            <li><a href="http://www.rfc-editor.org/info/rfc1572" target="_blank">RFC1572 Telnet Environment Option</a></li>
            <li><a href="http://www.rfc-editor.org/info/rfc1571" target="_blank">RFC1571 Telnet Environment Option Interoperability Issues</a></li>
            </ul>
        </td>
        <td style="border-style:none">    </td>
        <td style="border-style:none">
            <ul>
            <li><a href="http://www.rfc-editor.org/info/rfc856" target="_blank">RFC856 Telnet Binary Transmission</a></li>
            <li><a href="http://www.rfc-editor.org/info/rfc885" target="_blank">RFC885 Telnet end of record option</a></li>
            <li><a href="http://www.rfc-editor.org/info/rfc1576" target="_blank">RFC1576 TN3270 Current Practices</a></li>
            <li><a href="http://www.rfc-editor.org/info/rfc2355" target="_blank">RFC2355 TN3270 Enhancements</a></li>
            </ul>
        </td>
    </tr>
</table>
<p>
<a href="##" onclick="history.go(-1)"><img src="images/back.gif" border=0 alt="back"></a>


<br />
<h4 id="x3270">x3270 / c3270 / wc3270</h4>
<p>
    The x3270 family of tn3270 applications are available without charge
    from <a href="http://x3270.bgp.nu/" target="_blank">x3270.bgp.nu</a>.
    RPM's exist for many Linux distributions that use Redhat Package Manager files;
    <a href="https://www.rpmfind.net/linux/rpm2html/search.php?query=x3270" target="_blank">check here for a list</a>.
    It is also packaged for <a href="https://packages.debian.org/search?keywords=x3270" target="_blank">Debian</a>
    and <a href="http://packages.ubuntu.com/search?keywords=x3270" target="_blank">Ubuntu</a>,
    and the .deb packages can often be used with other Debian-based Linux distributions.
    They are licensed under the BSD license as shown on the
    <a href="http://x3270.bgp.nu/license.html">x3270 license page</a>.
</p>
<p>
    The packaged installation files available for Linux distributions are
    several minor releases older than the current stable release.
    You may wish to build x3270 from source even when an installation package
    exists for your Linux distribution.
    Build instructions for a variety of environments are in the
    Documentation - Miscelaneous page of the x3270 web site.
</p>
<p>
    The x3270 family includes the following applications (there are additional applications in the family; visit the x3270 site):
</p>
<ul>
    <li><b>x3270</b> - tn3270 for X11 servers driving graphical displays</li>
    <li><b>c3270</b> - tn3270 for fixed-function character-mode terminals or telnet sessions</li>
    <li><b>wc3270</b> - native Windows tn3270 application</li>
</ul>

<p>
    Start an x3270 session and connect to Hercules with the following.
</p><blockquote>
    <pre>
Windows: "c:\Program Files\wc3270\wc3270" -port nnnn -model 32xx-x hostname

Linux:   x3270 -port nnnn -model 32xx-x hostname
    </pre>
</blockquote>
<p>
    Replace the port, model, and hostname options as follows.
</p>
<table border="1" style="border-style:solid; padding:3px">
    <tr>
        <td>-port nnnn</td>
        <td>
            <p>
                This must match the port named in the Hercules configuration file
                CNSLPORT statement.
            </p>
        </td>
    </tr>
        <tr>
        <td>-model 32xx-x</td>
        <td>
            <ul>
                <li>3278-2   (a good second choice)</li>
                <li>3278-3</li>
                <li>3278-4</li>
                <li>3278-5</li>
                <li>3279-2   (recommended)</li>
                <li>3279-3</li>
            </ul>
            <p>
                Unless you know that the application program running
                under Hercules to which you will attach supports large
                screen sizes, specify 3279-2 or 3278-2 to select a 24 x 80 screen size.
            </p>
            <p>
                There's nothing wrong with a bit of trial and error here.
                Try other screen sizes to see what works.
                But start with a model 2.
            </p>
        </td>
    </tr>
    <tr>
        <td style="width:175px">hostname<br /><br />
            001f@hostname<br /><br />
            console@hostname</td>
        <td>
            <p>
                This identifies the ip address of the Hercules system and optionally the 3270 device in the Hercules configuration
                to which this session should connect.</p>
            <p>
                You can specify a host name, IPv4 address, or IPv6 address.&nbsp; Most commonly, you'll use localhost for the host name.&nbsp;
            </p>
            <p>
                If a hexadecimal number is provided before the host name, the session will try to
                connect to that address in the Hercules configuration. </p>
            <p>
                If a groupname is provided, the session will try to connect to
                any available 3270 device that names that group.
            </p>
            <p>
                If no name or number is provided before the host name,
                the session will connect to any available 3270 device.
            </p>
        </td>
    </tr>
</table>
<p>
    Example x3270 session startup command
</p><blockquote>
    <pre>
Windows: "c:\Program Files\wc3270\wc3270" -port 3270 -model 3229-2 localhost

Linux:   x3270 -port 3270 -model 3229-2 localhost
    </pre>
</blockquote>

<p>
    <a href="#pagetop">Return to top of page</a>
</p>


<br />
<h4 id="OSXtn3270">tn3270 for the Macintosh</h4>
<p>
    Tn3270 for the Macintosh is available without charge from Brown University at
    <a href="https://www.brown.edu/cis/tn3270/" target="_blank">https://www.brown.edu/cis/tn3270/</a>.
    According to the web site as of May, 2016,
    the current version of this tn3270 application can be used with
    OS X 10.3.9 "Panther" through OS X 10.9 "Mavericks"
    on POWER PC and Intel-based systems.
</p>
<p>
    Older versions of tn3270 exist for older Macintosh systems.
</p>
<p>
    This author does not have access to a Mac and regrets being unable to provide configuration options.
</p>
<p>
    <a href="#pagetop">Return to top of page</a>
</p>


<br />
<h4 id="Vistatn3270">Vista tn3270</h4>
<p>
    Vista tn3270 is a Windows application written and maintained by Tom Brennan,
    and is used by members of the Hercules community.
    You can learn more about it at <a href="http://www.tombrennansoftware.com/" target="_blank">Tom Brennan Software</a>.
    The screenshots are worth a look.
</p>
<p>
    Complete installation and setup instructions are included in the
    <a href="http://hercdoc.glanzmann.org/V400/HerculesInstallation.pdf" target="_blank">Hercules Installation Guide</a> for Hercules Version 4
    starting on page 123.
</p>
<p>
    <a href="#pagetop">Return to top of page</a>
</p>


<br /><h4 id="ZOCTerminal">ZOC Terminal</h4>
<p>
    ZOC Terminal, available for Windows and Macintosh, is offered by Emtec Innovative Software
    and is used by members of the Hercules community.
    You can learn more about it at the <a href="http://www.emtec.com/zoc/" target="_blank">ZOC Terminal</a> web site.
    The screenshots are worth a look.
</p>
<p>
    This author does not have access to a Mac and regrets being unable to provide configuration options.
</p>
<p>
    <a href="#pagetop">Return to top of page</a>
</p>


<br /><h4 id="PuTTY">PuTTY Telnet</h4>
<p>
    PuTTY version 0.67 has been tested on Windows and version 0.63
    has been tested on Debian 8.4.  Other recent versions of PuTTY should work as well.
</p>
<p>
    PuTTY source and Windows builds are available without charge and
    can be obtained from <a href="http://www.putty.org" target="_blank">putty.org</a>.
    RPM's exist for many Linux distributions that use Redhat Package Manager files;
    <a href="https://www.rpmfind.net/linux/rpm2html/search.php?query=putty" target="_blank">check here for a list</a>.
    It is also packaged for
    <a href="https://packages.debian.org/search?keywords=putty" target="_blank">Debian</a>
    and
    <a href="https://apps.ubuntu.com/cat/applications/oneiric/putty/" target="_blank">Ubuntu</a>,
    and the .deb packages can often be used on other linux distributions based on
    Debian.
    It is distributed under the MIT license,
    as shown on <a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/licence.html" target="_blank">
    PuTTY's license page</a>.
</p>
<p>
    The following options must be set for correct operation.&nbsp; Click on the page name to open a screen shot in a new browser window:
</p>
<blockquote>
    <table border="1" style="padding:10px">
        <tr>
            <th style="text-align:left">Page</th>
            <th style="text-align:left">Setting</th>
            <th style="text-align:left">Value needed for Hercules</th>
        </tr>
        <tr>
            <td rowspan="2"><a href="images/telnetputtysession.png" target="_blank">Session</a></td>
            <td>Port</td>
            <td>Must match nnnn in the CNSLPORT statement in the Hercules configuration file</td>
        </tr>
        <tr>
            <td>Connection type</td>
            <td>Select "Telnet"</td>
        </tr>
        <tr>
            <td rowspan="2"><a href="images/telnetputtyterminal.png" target="_blank">Terminal</a></td>
            <td>Local echo</td>
            <td>Select "Force on"</td>
        </tr>
        <tr>
            <td>Local line editing</td>
            <td>Select "Force on"</td>
        </tr>
        <tr>
            <td><a href="images/telnetputtyconndata.png" target="_blank">Connection - Data</a></td>
            <td>Terminal-type string</td>
            <td>Must be set to "ANSI"</td>
        </tr>
    </table>
</blockquote>
<p>
    Other options may be set as you wish.
    Because mainframes that used printer-keyboards used continuous forms,
    and "scrolling back" through the console log meant thumbing through a
    stack of continuous forms paper, you may wish to set the size of the
    window and the lines of scroll back on the Windows page to accomodate your preferences.
</p>
<p>
    <a href="#pagetop">Return to top of page</a>
</p>


<br />
<h4 id="nixtelnet">Linux telnet</h4>
<p>
    Virtually all Linux distributions come with a default telnet client
    that should work well out of the box.
    No special configuration should be needed.
</p>


<br />
<h4 id="Windows">Windows Telnet</h4>
<p>
    The Telnet client included with Windows is known to have been
    used successfully with Hercules Version 4. The telnet clients
    included with Windows XP, Vista, 7, 8, 8.1 and 10 appear to
    all be the same program, so the you should be able to set up a
    connection using the information below. Please post any difficulties to the
    <a href="https://hercules-390.groups.io/g/group" target="_blank">Hercules-390
    discussion group</a>, noting the symptoms, Windows version and error messages.
</p>
<p>
    One settings change is needed to use the Windows Telnet client with
    Hercules Version 4: '<b>set localecho</b>'. The defaults for the
    remaining settings should work.  Refer to the sample session below:
</p>
<blockquote>
<img src="images/telnetwin.png" border="0" alt="Windows Telnet settings" />
</blockquote>
<p>
    Window size and scroll-back are controlled by the command prompt window
    that Telnet is running in.  You can use the set logfile and set logging
    commands to record the Telnet session to a file.
</p>
<p>
    It is difficult to set up a connection profile to pre-define the
    <b>localecho</b> setting, the window size, and scroll-back.  For this
    reason, <a href="#PuTTY">PuTTY</a> is probably a better choice.
</p>
<p>
    <a href="#pagetop">Return to top of page</a>
</p>


<br />
<h4 id="WindowsNT">Windows NT Telnet</h4>
<p>
    There are many reasons not to use Windows NT Telnet to connect to Hercules.
    Specifically:
</p>
<ul style="">
    <li style="margin-bottom:10px">
        There are better solutions.  <a href="#PuTTY">PuTTY</a> for example.
    </li>
    <li style="margin-bottom:10px">
        Windows NT Telnet is licensed by Microsoft for use only when you have a
        valid Windows NT license. If you find a copy floating around on the Internet,
        it's not properly licensed.
    </li>
    <li style="margin-bottom:10px">
        If you do find it on the Internet, beware of the "gifts" that may have been added to the code.
    </li>
    <li>
        If you copy it from your NT installation CD, help does not work on Windows 10.
        And Hercules is not supported on Windows NT.
    </li>
</ul>
<p>
    If, after all that, you decide to crank up your NT workstation
    to Telnet to Hercules on a more modern system, here's how you do it:
</p>
<blockquote>
<table style="padding:15px 15px 15px 15px">
    <tr>
        <td style="padding:15px 15px 15px 15px">
            <img src="images/telnetwinntconnect.png" border="0" alt="Windows NT Telnet connect dialog" style="vertical-align:top" />
        </td>
        <td style="padding:15px 15px 15px 15px">
            <p>
                <em>Host Name:</em>
                You can use "@ccuu" following the host name to
                connect to a specific printer-keyboard address in the Hercules configuration file.  Example:
            </p>
            <pre>
                localhost@001f
            </pre>
            <p>
                <em>Port:</em> must match the value of the CNSLPORT statement in the Hercules configuration file.
                Although a drop-down box is shown, you can just type in a port number
            </p>
            <p>
                <em>TermType:</em> must be ANSI.
            </p>
        </td>
    </tr>
    <tr>
        <td style="padding:15px 15px 15px 15px">
            <img src="images/telnetwinnttermpref.png" border="0" alt="Windows NT Telnet terminal preferences dialog" style="vertical-align:top" />
        </td>
        <td style="padding:15px 15px 15px 15px">
            <p>
                <em><b>Local echo</b></em> must be checked under <em>Terminal Options</em>.
            </p>
            <p>
                <em>VT100/ANSI</em> must be selected for <em>Emulation</em>.
            </p>
        </td>
    </tr>
</table>
</blockquote>
<p>
    <a href="#pagetop">Return to top of page</a>
</p>

<p><center><hr width=15% noshade>
<a href="##" onclick="history.go(-1)"><img src="images/back.gif" border=0 alt="back"></a>
<p class="lastupd"><script language="Javascript">
document.write( "Last updated " + document.lastModified + "" );
</script></p>
</BODY>
</HTML>
